home *** CD-ROM | disk | FTP | other *** search
/ Amiga Plus Special 21 / AMIGAplus Sonderheft 21 (1999)(ICP)(DE)[!].iso / PublicDomain / Anwendungen / FBackNG / doc / fbackNG.doc next >
Text File  |  1999-08-23  |  23KB  |  576 lines
  1.  
  2.   *********************************************************************
  3.                               FBackNG V0.9.2
  4.                             By Chris De Maeyer
  5.                             For  AmigaDOS  68k
  6.   *********************************************************************
  7.  
  8.   !!!!!!!!!!!!!!!!!! BETA-BETA-BETA-BETA-BETA-BETA !!!!!!!!!!!!!!!!!!!!
  9.   !! NOT ALL FUNTIONS AND OPTIONS ARE IMPLEMENTED, AVAILABLE OPTIONS !!
  10.   !! ARE MARKED WITH *ACTIVE*, CLI PARSING IS FULLY IMPLEMENTED..... !!
  11.   !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
  12.  
  13.   0. Contents
  14.     ----------
  15.  
  16.      1. Introduction
  17.         1.1. Legal
  18.         1.2. Shareware
  19.         1.3. What it does...
  20.         1.4. Requirements
  21.         1.5. Contact address
  22.         1.6. Development info
  23.         1.7. Versions
  24.  
  25.      2. Using it
  26.         2.1. Command line options
  27.         2.2. Examples
  28.  
  29.      3. Appendix
  30.         3.1. Common problems
  31.         3.2. Error messages
  32.         3.3. The future
  33.  
  34.  
  35.   1. Introduction
  36.     --------------
  37.  
  38.      If you have used this program before try to make the effort to read this doc
  39.      again. Some useful info is updated, not listed in previous versions.
  40.      
  41.      The program is a complete rewrite of a program formerly known as FBack/FMirror.     
  42.  
  43.  
  44.      1.1. Legal
  45.          -------
  46.           Type  : - SHAREWARE.
  47.  
  48.           Terms : - no modifications to any file in this distribution archive.
  49.                   - add no additional files to the distribution archive.
  50.                   - use this program longer than 30 days, then you should reward
  51.                     the author with a shareware fee.
  52.                   - after registering you will receive your personal keyfile, this
  53.                     keyfile will enable all options. The keyfile is valid for all
  54.                     remaining versions which are named 'FBackNG'.  
  55.                   - author can not be held responsible for data loss, the program
  56.                     has been tested and the behaviour has been described below.
  57.                   - any commercial distribution is prohibited.
  58.                   - the unregistered version may be freely distributed on cover
  59.                     disks and compact discs.
  60.                   - the keyfile is personal and coded with the registered user's
  61.                     name and may not be distributed in any way.  
  62.                   - by registering the user accepts all above mentioned rights
  63.                     and obligations.
  64.                     
  65.  
  66.      1.2. Shareware
  67.          -----------
  68.          
  69.          The unregistered version has following restrictions:
  70.          
  71.                 - shareware banner pauses
  72.                 - recursive option disabled.
  73.                 
  74.                 
  75.          Rate:    USD 15  for delivery by email
  76.                   USD 20  for delivery by mail (Europe - EEG)
  77.                   USD 25  for delivery by mail (rest of world).
  78.                   
  79.                   Payment with cash in USD (no coins), or EUR according to
  80.                   exchange rates. Or via Eurocheque in USD/EUR.
  81.                   
  82.                   Fill out the registration form and mail with necessary
  83.                   funding. Make sure you specify all information.
  84.                   
  85.                   
  86.  
  87.      1.3. What it does
  88.          --------------
  89.           'FBackNG' is a daily backup tool. It will check files and copy them
  90.           to your backup location if they changed. Additionally it runs a scan
  91.           between the original location and the backup, and updates the backup
  92.           creating a mirror this way. Working in this fashion will get you up
  93.           and running again after HD problems/replacement. See example section
  94.           for common usages.
  95.           
  96.           The program includes a batch mode, paths and options are then specified
  97.           with a configuration file. Several location entries are allowed.
  98.  
  99.  
  100.           Changes (in relation to FBack/FMirror V1.8):
  101.           
  102.  
  103.           - complete rewrite of directory/file parser to support any partition
  104.             size with any number of files.
  105.  
  106.           - added features to enhance portability (standard ANSI functions and
  107.             UNIX command line parsing).
  108.  
  109.           - the program now comprises the two functionalities of the fback/fmirror
  110.             suite, one program serves all. The program will now run in phases.
  111.             First a backup phase will run which saves all changed files, then
  112.             if you specify it, a mirror phase is executed. It will synchronise
  113.             the backup with the original. You can also specify to skip backup
  114.             phase and only run a mirror phase.
  115.            
  116.           - extra care has been taken to make it idiot proof, extensive reporting
  117.             and distinct error detection to make troubleshooting easier.
  118.            
  119.            
  120.  
  121.      1.4. Requirements
  122.          --------------
  123.           Properly installed Amiga (haven't we all!). To use compression you will
  124.           need the XPK library and tools.
  125.  
  126.  
  127.  
  128.      1.5. Contact address
  129.          -----------------
  130.           For mail/information/problems/registrations/bugs write to the address
  131.           below, state version & add postage for reply:
  132.  
  133.                  Visionary Software
  134.                  tav. Chris De Maeyer
  135.  
  136.                  Norbertijnenstraat 4
  137.                  B-2040       BELGIUM
  138.                  EUROPE - WORLD - UNIVERS
  139.  
  140.                  Internet :ceppe@pandora.be
  141.                            http://users.pandora.be/ceppe
  142.                            (latest updates will be here first!)        
  143.  
  144.  
  145.      1.6. Development info
  146.          ------------------
  147.           Sources were written in C and compiled using SAS/C V6.58.
  148.           Part of file I/O has been coded using standard system library functions.
  149.           Where possible ANSI functions were used. This surely makes it a bit slower.
  150.           This version was developed with portability in mind. The old program had a GUI
  151.           part, which has been removed completely in this one. This also for portability.
  152.  
  153.  
  154.  
  155.      1.7. Versions
  156.          ----------
  157.         
  158.           The actual version can be determined by typing 'version fbackng' in a
  159.           CLI window. It is recommended to always upgrade to the latest version.
  160.  
  161.  
  162.           V0.9.0  BETA RELEASE
  163.           
  164.                   - command parser introduced.
  165.                   - file/directory parser introduced.
  166.                   - copy routine introduced, but see below...
  167.                   - some debug code enabled.
  168.                   - limited version which takes no action other than parsing the
  169.                     command line and then scanning the filesystems.
  170.  
  171.           V0.9.1  BETA RELEASE
  172.  
  173.                   - file functions (set flags, clone comment/date, etc).
  174.                   - every file is checked on destination before copy is done, and
  175.                     action is taken.
  176.                   - file/directory parser changed to host both backup and
  177.                     mirror phases.
  178.                   - increased file/directory parser temp. allocation.  
  179.                   - stack 64kb and compiled with STACKEXTEND.
  180.                   - simulate switch implemented.
  181.                   - skip backup phase switch implemented.
  182.                   - nonotes switch implemented.
  183.                   - touch switch implemented.                  
  184.                   - logfile option implemented.
  185.                   - compress option implemented.
  186.                   - backup phase is implemented.
  187.                   - cleaned up all reported compiler optimizations.                  
  188.                           
  189.           V0.9.2  BETA RELEASE
  190.           
  191.                   - file/parser handler changed to handle full paths.
  192.                   - enabled security.
  193.                                                          
  194.                                                                    
  195.   2. Using it
  196.     ----------
  197.      2.1. Command line options
  198.          ----------------------
  199.           The program uses standard UNIX command templates, so typing 'FBackNG -h'
  200.           will list all the options available.
  201.  
  202.           Unix options are of the form:
  203.           
  204.                 -<letter>               for flags
  205.                 -<letter> <value>       for parameters
  206.                 -<letter><letter>...    for flags
  207.                 
  208.                 fe. -e
  209.                     -b thevalue
  210.                     -tmr    
  211.                 
  212.           Options are free form, meaning they can be typed in without taking in
  213.           account the sequence in which they appear.
  214.           Options are CASE SENSITIVE.
  215.           
  216.           See example section [2.2].
  217.  
  218.  
  219.  
  220.           Command template
  221.           ================
  222.           
  223.                 FBackNG [-b <backup from source path>] [-o <to destination>]
  224.                         [-h] [-s] [-r] [-v <0|1|2|3>] [-i <pri>] [-c <packer>]
  225.                         [-e] [-t] [-n] [-f <file>]
  226.                         [-a <pattern>] [-l <file>]
  227.                         [-a <date>] [-A <date>]
  228.                         [-y <date>] [-Y <date>]
  229.                         [-m][-k]
  230.                         
  231.                         
  232.           Detail explanation of options
  233.           =============================
  234.  
  235.              h            - display HELP.
  236.                             
  237.                             (*ACTIVE*)
  238.                             
  239.                                      
  240.              b <path>     - the full path of the SOURCE directory (what to backup).
  241.                             
  242.                             fe. sys:
  243.                                 work:data
  244.                                 
  245.                             (*ACTIVE*)
  246.              
  247.              
  248.              o <path>     - the full path of the DESTINATION directory (where to backup).
  249.                             
  250.                             fe. dh1:mirror/sys
  251.                                 backup:
  252.                                 
  253.                             (*ACTIVE*)
  254.              
  255.                                      
  256.              s            - Adding this flags will merely report action it would take
  257.                             if this flag was not active. Call it a SIMULATE mode.
  258.  
  259.                             (*ACTIVE*)
  260.              
  261.                             
  262.              r            - include subdirectories RECURSIVE.
  263.                             
  264.                             (*ACTIVE*)
  265.              
  266.                             
  267.              v <0|1|2|3>  - specify the output sent to the user, level of VERBOSITY.
  268.  
  269.                                 0 = no output
  270.                                 1 = normal output (default)
  271.                                 2 = detail output
  272.                                 3 = debug output
  273.                             
  274.                             Note on performance: the more you send to the console,
  275.                             the slower the program will work. To get optimal speed
  276.                             specify option 0, or let the output write to file using
  277.                             the -l option.
  278.                             
  279.                             (*ACTIVE*)
  280.              
  281.                                 
  282.              i <pri>      - set PRIORITY (-100 to 5), in the old days you could
  283.                             use a task manager to do this, now you can simply add
  284.                             it as an option either to speed-up or let it creep in
  285.                             the background.
  286.              
  287.                             Q: Why I've put in a min. and max. ?
  288.                             A: To avoid problems. As a Amiga guy you should know that
  289.                                setting priorities wrong can give strange results. Fe.
  290.                                program keeps running and doesn't react to input anymore.
  291.                                Eg. console.device runs at priority 5 etc.
  292.                     
  293.                             
  294.              c <packer>   - enables COMPRESSION mode, supply preferred packer. In this
  295.                             mode make sure your recovery disk includes the XPK library
  296.                             + some XPK unpacker (fe. xpk [included]) to restore files.
  297.                             
  298.                                 fe. -c nuke
  299.                                 
  300.                             (*ACTIVE*)
  301.                             
  302.                                           
  303.              e            - specifying this option will ignore the archive bit, thus
  304.                             copying EVERY file (= full backup).
  305.                             
  306.                             (*ACTIVE*)
  307.                            
  308.                            
  309.              t            - updates date/time on destination, TOUCH it with current
  310.                             system date/time. If not specified the program will clone
  311.                             date/time from source. Remark: time set is not localized.
  312.  
  313.                             (*ACTIVE*)
  314.                             
  315.                             
  316.              n            - specifying this option will instruct NOT to copy the
  317.                             filenotes. By default comments are copied.
  318.  
  319.                             (*ACTIVE*)
  320.                             
  321.                              
  322.              f <file>     - run in batch mode, this parameter contains the FILENAME
  323.                             of the configuration file to process. 
  324.                             
  325.                             Syntax configuration file (text file):
  326.                             
  327.                             ----------------- cut ----------------------
  328.                                 [FBackNG]
  329.                                 NumberOfPaths = <N>
  330.                                 
  331.                                 [Paths]
  332.                                 OrgPath1 = <source path 1>
  333.                                 BckPath1 = <destination path 1>
  334.                                 Options1 = <options>
  335.                                 ...
  336.                                 OrgPathN = <source path N>
  337.                                 BckPathN = <destination path N>
  338.                                 OptionsN = <options>                                
  339.                             
  340.                             ----------------- cut ----------------------
  341.                                  
  342.                             Example: study "MYBACK.CFG" included in the archive.
  343.                             
  344.                                 
  345.             g <pattern>   - only process files which match the PATTERN.
  346.  
  347.                             (*ACTIVE*)
  348.                             
  349.                                 
  350.             l <file>      - write generated output to a LOG file. The log contains
  351.                             output of level DETAIL.
  352.                             
  353.                             (*ACTIVE*)
  354.                             
  355.                                 
  356.             y <date>      - only backup files BEFORE given date (incl.date)
  357.             Y <date>      -  "     "      "     "      "    "   (not incl.date)
  358.                  
  359.                             DATES ARE IN ADOS FORMAT = DD-MMM-YYYY
  360.                                                    eg. 23-jun-1998               
  361.  
  362.                            
  363.             a             - only backup files AFTER  given date (incl. date).
  364.             A             -  "     "      "     "      "    "   (not incl.date)
  365.  
  366.             
  367.             m             - after backup run a MIRROR phase.
  368.  
  369.                                       
  370.             k             - do not run a BACKUP phase, obviously specifying this
  371.                             option without the m option is invalid.
  372.                         
  373.                           (*ACTIVE*)
  374.                  
  375.                  
  376.      2.2. Examples
  377.          ----------
  378.           This section lists some examples of usage. If you have scenarios of your
  379.           own then send them in, to help others I'll include them here.
  380.  
  381.           - Backup changed prefs files:
  382.  
  383.                ; Startup-sequence
  384.                ...
  385.                fbackng -m -v 0 -r -b sys:prefs/env-archive -o work:backup/prefs 
  386.                ...
  387.  
  388.           - Backup and mirror a disk at startup & add to logfile:
  389.  
  390.                ; Startup-sequence
  391.                ...
  392.                fbackng -rm -b sys: -o mirror:boot -l T:FBack.log
  393.                ...
  394.                
  395.  
  396.           - Backup and mirror files before shutdown:
  397.           
  398.                .key FLAG
  399.                .bra {
  400.                .ket }
  401.                ; Shutdown script
  402.                echo "Just a moment, valuable files are checked..."
  403.                ;
  404.                if {FLAG} EQ "GFX"
  405.                     fbackng -r -b work:data/gfx -o backup:data/gfx -v 0
  406.                     echo "Gfx data has been saved."
  407.                endif
  408.                if {FLAG} EQ "ALL"
  409.                     fbackng -r -m -b work:data -o mirror:data -v 0
  410.                     echo "All data has been mirrored."
  411.                endif
  412.                ;
  413.                fbackng -rm -b sys:prefs -o mirror:prefs -c blzw -v 0
  414.                echo "System preferences have been saved."
  415.                ; 
  416.                if exists C:Halt
  417.                     echo "It now safe to switch me OFF !"
  418.                     Halt 
  419.                endif
  420.  
  421.           - Backup certain files in a range of dates:
  422.           
  423.                fbackng -r -b data:texts -o backup: -t -a 01-feb-1999 -y 10-feb-2000
  424.                
  425.             Will backup the files from 01 february 1999 till 09 february 2000.
  426.  
  427.                
  428.                
  429.   3. Appendix
  430.     ----------
  431.      3.1. Common problems
  432.          -----------------
  433.  
  434.           Q: When I backup to a JAZ/ZIP drive it takes a long time !
  435.           
  436.           A: Add a large number of disk buffers, eg. 'AddBuffers JAZ5: 2000'.
  437.              This is not caused by FBack, but due to the way JAZ/ZIP works.          
  438.  
  439.  
  440.  
  441.           Q: I'm a bit confused by the options, how do I only mirror ?
  442.           
  443.           A: Specify as options -km, then the backup phase is skipped, and
  444.              a mirror phase is triggered.
  445.           
  446.           
  447.           
  448.      3.2. Error messages (Hmmm, your finger slipped ? Or something more serious...)
  449.          --------------------------------------------------------------------------
  450.  
  451.           ARGUMENT/COMMAND LINE ERRORS
  452.           ============================
  453.  
  454.           fbackng: fatal: invalid argument-- %c
  455.           
  456.                 You substituted and invalid commandline option. Review your
  457.                 commandline.
  458.          
  459.                 
  460.           fbackng: fatal: argument required for %c
  461.           
  462.                 You typed a commandline option which requires a value. Review
  463.                 your commandline and substitute a value for the option.      
  464.          
  465.                                                               
  466.           fbackng: fatal: source or destination path required
  467.           
  468.                 When batch mode is not active it is necessary to define the
  469.                 options -b,-o to set the original path and backup path.
  470.                 
  471.                 Review the commandline and issue:
  472.                 
  473.                          -b source -o destination
  474.                 
  475.                 in the commandline.
  476.          
  477.          
  478.          
  479.           PROCESSING ERRORS
  480.           =================
  481.           
  482.           fbackng: fatal: backup process error (n)
  483.           
  484.                 FBackNG encountered an error while searching and processing
  485.                 the filesystem and this in the backup phase.
  486.                 
  487.                 
  488.           fbackng: fatal: mirror process error (n)
  489.           
  490.                 FBackNG encountered an error while searching and processing
  491.                 the filesystem this during the mirror phase.
  492.                  
  493.                 
  494.           Overview of error return codes relating to processing:
  495.                 
  496.                 Error    Description
  497.                 -------------------------------------------------------------
  498.                 1        Could not lock directory, a directory could not be
  499.                          locked for examining. Try to reboot your system or
  500.                          closing all applications, then try again.
  501.                          
  502.                 2        Memory allocation error, if you have limited memory
  503.                          then this can occur.  
  504.                                                   
  505.                 3        Allocation of DosObject failed.
  506.                 
  507.                 5        Could not open destination file. Disk full ?
  508.           
  509.                 6        Error while copying source to destination. Check
  510.                          protect bits on destination.
  511.                          
  512.                 9        Could not lock a file. It may be in use by another
  513.                          process. Try rebooting, then retry.
  514.                          
  515.                 10       Could not get file information. Errors 10 upto 18
  516.                          could indicate a corrupt file or filesystem.
  517.                 
  518.                 11       Error cloning file datestamp.
  519.                 
  520.                 12       Error deleting file.
  521.                 
  522.                 13       Could not set archive flag on file.
  523.                 
  524.                 14       Could not set comment on file.                  
  525.           
  526.                 15       Error cloning protect flags.
  527.                 
  528.                 16       System datestamp could not be set.
  529.                 
  530.                 17       Volume not found.
  531.                 
  532.                 18       Could not set delete flag on file.
  533.                 
  534.           
  535.           
  536.           LOGGING ERRORS
  537.           ==============
  538.                          
  539.           fbackng: fatal: could not initiate log (n)
  540.          
  541.                 FBackNG encountered an error while attempting to access the
  542.                 logfile for the first time.
  543.                 
  544.                 
  545.           fbackng: fatal: cannot write to log <file> (n)
  546.          
  547.                 FBackNG got an error writing to the log.
  548.                 
  549.                 
  550.                 
  551.           Overview of logfile related error return codes:
  552.                 
  553.                 Error    Description
  554.                 ------------------------------------------------------------
  555.                 7        The logfile could not be opened. It could be locked
  556.                          by another process. Try identifying the lock, either
  557.                          close all running processes, or reboot. Then, retry.
  558.                 
  559.                 8        An error occurred while writing to the logfile. This
  560.                          could indicate a DOS error, ie. protection, no more
  561.                          space, etc. Examine your filesystem and make sure 
  562.                          enough resources are available.
  563.                                                           
  564.                                   
  565.                                   
  566.      3.3. The future
  567.          ------------
  568.  
  569.           When its all finished It'll probably need a GUI frontend...
  570.           
  571.           Any suggestions/motivations/gifts from you are welcome !
  572.           
  573.           Thanks to all guys & dolls sending me registrations.
  574.  
  575.           It is because of YOU this program keeps getting better and better...
  576.